Level-specific files

Functions and callbacks for level-specific logic scripts.

Ambience and music

SetAmbientTrack(name) Set and play an ambient track
PlayAudioTrack(name, loop) Play an audio track

Player inventory management

GiveInvItem(item, count) Add x of an item to the inventory.
TakeInvItem(item, count) Remove x of a certain item from the inventory.
GetInvItemCount(item) Get the amount the player holds of an item.
SetInvItemCount(item, count) Set the amount of a certain item the player has in the inventory.

Game entity getters

GetItemByName(name) Get an ItemInfo by its name.
GetMeshByName(name) Get a MeshInfo by its name.
GetCameraByName(name) Get a CameraInfo by its name.
GetSinkByName(name) Get a SinkInfo by its name.
GetSoundSourceByName(name) Get a SoundSourceInfo by its name.
CalculateDistance(posA, posB) Calculate the distance between two positions.
CalculateHorizontalDistance(posA, posB) Calculate the horizontal distance between two positions.

Special objects

Lara An ItemInfo representing Lara herself.

Special tables

LevelVars A table with level-specific data which will be saved and loaded.
GameVars A table with game data which will be saved and loaded.
LevelFuncs A table with level-specific functions.


Ambience and music

SetAmbientTrack(name)
Set and play an ambient track

Parameters:

  • name string of track (without file extension) to play
PlayAudioTrack(name, loop)
Play an audio track

Parameters:

  • name string of track (without file extension) to play
  • loop bool if true, the track will loop; if false, it won't (default: false)

Player inventory management

GiveInvItem(item, count)
Add x of an item to the inventory. A count of 0 will add the "default" amount of that item (i.e. the amount the player would get from a pickup of that type). For example, giving "zero" crossbow ammo would give the player 10 instead, whereas giving "zero" medkits would give the player 1 medkit.

Parameters:

  • item InvItem the item to be added
  • count int the number of items to add (default: 0)
TakeInvItem(item, count)
Remove x of a certain item from the inventory. As in GiveInvItem, a count of 0 will remove the "default" amount of that item.

Parameters:

  • item InvItem the item to be removed
  • count int the number of items to remove (default: 0)
GetInvItemCount(item)
Get the amount the player holds of an item.

Parameters:

  • item InvItem the item to check

Returns:

    int the amount of the item the player has in the inventory
SetInvItemCount(item, count)
Set the amount of a certain item the player has in the inventory. Similar to GiveInvItem but replaces with the new amount instead of adding it.

Parameters:

  • item the item to be set
  • count int the number of items the player will have

Game entity getters

All Lua variables created with these functions will be non-owning. This means that the actual in-game entity (object/camera/sink/whatever) will not be removed from the game if the Lua variable goes out of scope or is destroyed in some other way.
GetItemByName(name)
Get an ItemInfo by its name.

Parameters:

  • name string the unique name of the item as set in, or generated by, Tomb Editor

Returns:

    ItemInfo a non-owning ItemInfo referencing the item.
GetMeshByName(name)
Get a MeshInfo by its name.

Parameters:

  • name string the unique name of the mesh as set in, or generated by, Tomb Editor

Returns:

    MeshInfo a non-owning MeshInfo referencing the mesh.
GetCameraByName(name)
Get a CameraInfo by its name.

Parameters:

  • name string the unique name of the camera as set in, or generated by, Tomb Editor

Returns:

    CameraInfo a non-owning CameraInfo referencing the camera.
GetSinkByName(name)
Get a SinkInfo by its name.

Parameters:

  • name string the unique name of the sink as set in, or generated by, Tomb Editor

Returns:

    SinkInfo a non-owning SinkInfo referencing the sink.
GetSoundSourceByName(name)
Get a SoundSourceInfo by its name.

Parameters:

  • name string the unique name of the sink as set in, or generated by, Tomb Editor

Returns:

    SoundSourceInfo a non-owning SoundSourceInfo referencing the sink.
CalculateDistance(posA, posB)
Calculate the distance between two positions.

Parameters:

  • posA Position first position
  • posB Position second position

Returns:

    int the direct distance from one position to the other
CalculateHorizontalDistance(posA, posB)
Calculate the horizontal distance between two positions.

Parameters:

  • posA Position first position
  • posB Position second position

Returns:

    int the direct distance on the XZ plane from one position to the other

Special objects

Lara
An ItemInfo representing Lara herself.

Special tables

TombEngine uses the following tables for specific things.
LevelVars
A table with level-specific data which will be saved and loaded. This is for level-specific information that you want to store in saved games.

For example, you may have a level with a custom puzzle where Lara has to kill exactly seven enemies to open a door to a secret. You could use the following line each time an enemy is killed:

LevelVars.enemiesKilled = LevelVars.enemiesKilled + 1

If the player saves the level after killing three, saves, and then reloads the save some time later, the values 3 will be put back into LevelVars.enemiesKilled.

This table is emptied when a level is finished. If the player needs to be able to return to the level (like in the Karnak and Alexandria levels in The Last Revelation), you will need to use the GameVars table, below.

GameVars
A table with game data which will be saved and loaded. This is for information not specific to any level, but which concerns your whole levelset or game, that you want to store in saved games.

For example, you may wish to have a final boss say a specific voice line based on a choice the player made in a previous level. In the level with the choice, you could write:

GameVars.playerSnoopedInDraws = true

And in the script file for the level with the boss, you could write:

if GameVars.playerSnoopedInDraws then
    PlayAudioTrack("how_dare_you.wav")
end

Unlike LevelVars, this table will remain intact for the entirety of the game.

LevelFuncs
A table with level-specific functions.

This serves two purposes: it holds the level callbacks (listed below) as well as any trigger functions you might have specified. For example, if you give a trigger a Lua name of "my_trigger" in Tomb Editor, you will have to implement it as a member of this table:

LevelFuncs.my_trigger = function()
    -- implementation goes here
end

The following are the level callbacks. They are optional; if your level has no special behaviour for a particular scenario, you do not need to implement the function. For example, if your level does not need any special initialisation when it is loaded, you can just leave out LevelFuncs.OnStart.

Fields:

  • OnStart function Will be called when a level is loaded
  • OnLoad function Will be called when a saved game is loaded
  • OnControlPhase function(float) Will be called during the game's update loop, and provides the delta time (a float representing game time since last call) via its argument.
  • OnSave function Will be called when the player saves the game
  • OnEnd function Will be called when leaving a level. This includes finishing it, exiting to the menu, or loading a save in a different level.
generated by LDoc 1.4.6 Last updated 2021-08-23 20:14:37